<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Opening multiple databases in a single file</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="am.html" title="Chapter 3.  Access Method Operations" />
    <link rel="prev" href="am.html" title="Chapter 3.  Access Method Operations" />
    <link rel="next" href="am_partition.html" title="Partitioning databases" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Opening multiple databases in a
        single file</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="am.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 3.  Access Method Operations </th>
          <td width="20%" align="right"> <a accesskey="n" href="am_partition.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="am_opensub"></a>Opening multiple databases in a
        single file</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="am_opensub.html#idm140526457459376">Configuring databases sharing a file</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="am_opensub.html#idm140526460261584">Caching databases sharing a file</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="am_opensub.html#idm140526459479920">Locking in databases based on sharing a file</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
        Applications may create multiple databases within a single
        physical file. This is useful when the databases are both
        numerous and reasonably small, in order to avoid creating a
        large number of underlying files, or when it is desirable to
        include secondary index databases in the same file as the
        primary index database. Putting multiple databases in a single
        physical file is an administrative convenience and unlikely to
        affect database performance.
    </p>
      <p>
        To open or create a file that will include more than a
        single database, specify a database name when calling the
        <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a> method.
    </p>
      <p>
        Physical files do not need to be comprised of a single type
        of database, and databases in a file may be of any mixture of
        types, except for Queue and Heap databases. Queue and Heap
        databases must be created one per file and cannot share a file
        with any other database type. There is no limit on the number
        of databases that may be created in a single file other than
        the standard Berkeley DB file size and disk space
        limitations.
    </p>
      <p>
        It is an error to attempt to open a second database in a
        file that was not initially created using a database name,
        that is, the file must initially be specified as capable of
        containing multiple databases for a second database to be
        created in it.
    </p>
      <p>
        It is not an error to open a file that contains multiple
        databases without specifying a database name, however the
        database type should be specified as DB_UNKNOWN and the
        database must be opened read-only. The handle that is returned
        from such a call is a handle on a database whose key values
        are the names of the databases stored in the database file and
        whose data values are opaque objects. No keys or data values
        may be modified or stored using this database handle.
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idm140526457459376"></a>Configuring databases sharing a file</h3>
            </div>
          </div>
        </div>
        <p>
            There are four pieces of configuration information which
            must be specified consistently for all databases in a
            file, rather than differing on a per-database basis. They
            are: byte order, checksum and encryption behavior, and
            page size. When creating additional databases in a file,
            any of these configuration values specified must be
            consistent with the existing databases in the file or an
            error will be returned.
        </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idm140526460261584"></a>Caching databases sharing a file</h3>
            </div>
          </div>
        </div>
        <p>
            When storing multiple databases in a single physical
            file rather than in separate files, if any of the
            databases in a file is opened for update, all of the
            databases in the file must share a memory pool. In other
            words, they must be opened in the same database
            environment. This is so per-physical-file information
            common between the two databases is updated
            correctly.
        </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idm140526459479920"></a>Locking in databases based on sharing a file</h3>
            </div>
          </div>
        </div>
        <p>
            If databases are in separate files (and access to each
            separate database is single-threaded), there is no reason
            to perform any locking of any kind, and the two databases
            may be read and written simultaneously. Further, there
            would be no requirement to create a shared database
            environment in which to open those two databases.
        </p>
        <p>
            However, since multiple databases in a file exist in a
            single physical file, opening two databases in the same
            file simultaneously requires locking be enabled, unless
            all of the databases are read-only. As the locks for the
            two databases can only conflict during page allocation,
            this additional locking is unlikely to affect performance.
            The exception is when Berkeley DB Concurrent Data Store is
            configured; a single lock is used for all databases in the
            file when Berkeley DB Concurrent Data Store is configured,
            and a write to one database will block all accesses to all
            databases.
        </p>
        <p>
            In summary, programmers writing applications that open
            multiple databases in a single file will almost certainly
            need to create a shared database environment in the
            application as well. For more information on database
            environments, see <a class="xref" href="env.html#env_intro" title="Database environment introduction">Database environment introduction</a>
        </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="am.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="am.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="am_partition.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Chapter 3.  Access Method Operations  </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Partitioning databases</td>
        </tr>
      </table>
    </div>
  </body>
</html>
